feat(herdr): apply mate naming convention to workspace/tab labels - #30

Intent

Implement a herdr workspace/tab naming convention so the captain can visually distinguish fleet supervisors (mates) from workers (crewmates) in herdr's UI at a glance. Convention: mate agents (persistent supervisors -- main firstmate plus every second/third mate) get workspace name AND tab name = {materank}-{scope}, ALWAYS UPPERCASE. materank: 1M=first mate/main firstmate, 2M=second mate, 3M=third mate. scope: the mate's domain (e.g. BEADME, PARLAY for second mates); main firstmate defaults to 1M-FIRSTMATE. Subordinate crewmates (workers spawned by any mate) are LOWERCASE, using the pre-existing fm- task label -- deliberately distinct from uppercase mate names and never colliding with one. Implementation: bin/backends/herdr.sh gets a new fm_backend_herdr_mate_scope helper (uppercases the secondmate marker id, sanitizes non-alphanumeric runs to a single dash, trims leading/trailing dashes, falls back to the literal UNKNOWN when empty/unreadable so a malformed marker can never impersonate the primary or collide) and fm_backend_herdr_workspace_label was rewritten to use it, producing 1M-FIRSTMATE for the primary home (no secondmate marker) and 2M- for a secondmate home. The projection-ordering jq helper is_top_level_parent was extended to also recognize the new ^[0-9]+M-[A-Z0-9-]+$ label shape while the old is_legacy_child matcher is deliberately left frozen (old-format-only) so a new-format parent can never spuriously match it -- this is a decision to keep old and new formats simultaneously recognized rather than migrating. bin/fm-spawn.sh was changed so a --secondmate spawn's own live-agent tab is labeled with the mate label (via fm_backend_herdr_workspace_label) instead of the ordinary fm- crewmate label; ordinary crewmate/scout spawns are unchanged. Docs (docs/herdr-backend.md new 'Mate naming convention' section, docs/configuration.md) were updated, including an explicit decision that pre-existing/older workspaces using the old firstmate/2ndmate- labels are NOT auto-migrated -- a captain must rename them manually, and this is called out as an intentional non-goal, not an oversight. Tests updated: fm-backend-herdr.test.sh (unit coverage for fm_backend_herdr_mate_scope and fm_backend_herdr_workspace_label, including the UNKNOWN fallback and uppercase-mate/lowercase-crewmate distinction), plus fake-herdr-binary label literals updated across fm-backend-herdr-launcher-workspace-e2e.test.sh, fm-backend-herdr-smoke.test.sh, fm-backend-herdr-workspace-per-home-e2e.test.sh, and fm-backend-herdr-presentation-e2e.test.sh (all e2e/smoke files were only syntax-checked via bash -n per this repo's hard safety rule against ever executing real-Herdr-lifecycle test paths by hand -- they are gated to skip without a live herdr binary). Also fixed a genuine regression surfaced only by actually running fm-session-start.test.sh: its make_fake_herdr_secondmate_recovery fake CLI's canned 'workspace list' response still hardcoded the OLD 2ndmate- label format, so bin/fm-bootstrap.sh's secondmate-liveness-sweep respawn path (which now searches for an existing workspace matching the NEW computed label before creating one) never found a match and failed; fixed by updating that fixture to emit the new 2M- format. Other backends (tmux, cmux, zellij) are confirmed unaffected -- this is a herdr-only change; fm-backend-cmux.test.sh and fm-backend-zellij.test.sh use their own independent, pre-existing 2ndmate- home-labeling convention unrelated to herdr's mate naming and were left untouched. All mocked/fakebin-based herdr test suites pass locally (145+33+41+ ok across files) and bin/fm-lint.sh is clean. PR should NOT be merged -- captain will review and merge manually.

What Changed

• Added fm_backend_herdr_mate_scope to bin/backends/herdr.sh and rewrote fm_backend_herdr_workspace_label to use it, producing uppercase 1M-FIRSTMATE for the primary home and 2M-<SCOPE> for a secondmate home (sanitizing non-alphanumeric runs, trimming dashes, falling back to UNKNOWN on an empty/unreadable marker), while ordinary crewmate/scout labels remain the lowercase fm-<id> form.
• Extended the projection-ordering is_top_level_parent jq helper to also recognize the new ^[0-9]+M-[A-Z0-9-]+$ label shape alongside the frozen legacy is_legacy_child matcher, and updated bin/fm-spawn.sh so a --secondmate spawn's live-agent tab is labeled with the mate label instead of the ordinary crewmate label.
• Updated docs/herdr-backend.md and docs/configuration.md with a new mate naming convention section (including the explicit non-migration of pre-existing old-format workspaces), fixed a stale doc-comment label reference, noted that frozen herdr E2E evidence predates this convention, and updated unit/e2e/smoke test fixtures across the herdr test suite (plus a fm-session-start.test.sh fixture regression fix for the secondmate-liveness-sweep respawn path).

Risk Assessment

✅ Low: Change is a well-scoped, mechanical relabeling confined to the herdr backend (new fm_backend_herdr_mate_scope helper, updated workspace_label, and a HERDR_TASK_LABEL override for --secondmate spawns); it correctly fixes a real prior bug (an empty/malformed secondmate marker could previously impersonate the primary's "firstmate" label), the projection-ordering jq matcher is extended additively without breaking legacy-format recognition, and all touched test fixtures (unit, e2e, smoke) were updated consistently and verified against the new format including the genuine fm-session-start.test.sh fixture regression the author already caught and fixed.

Testing

Ran the two automated unit suites that changed for this feature (fm-backend-herdr.test.sh and fm-session-start.test.sh), both 100% passing including the new mate-naming-convention unit tests and the specific secondmate-liveness-sweep regression test the author fixed; syntax-checked the four e2e/smoke herdr test files without executing them (consistent with the repo's hard rule against running real Herdr lifecycle by hand, and a real herdr binary is installed here); and produced a CLI transcript that directly exercises the production label-computation code end-to-end, confirming the primary home resolves to 1M-FIRSTMATE, secondmate homes resolve to distinct uppercase 2M-<SCOPE> labels with correct sanitization and UNKNOWN fallback for malformed/blank markers, ordinary crewmate labels remain lowercase and are never misidentified as a mate workspace, and the projection-ordering jq helper accepts both the new and legacy label formats. No failures or missing-evidence gaps found.

=== Demonstrating the herdr mate naming convention: workspace/tab labels a captain sees in herdr's UI ===

-- Primary firstmate home (no secondmate marker) --
workspace/tab label: 1M-FIRSTMATE

-- Second mate home, scope 'beadme' --
workspace/tab label: 2M-BEADME

-- Second mate home, scope 'parlay' (distinct from beadme's) --
workspace/tab label: 2M-PARLAY

-- Second mate home, messy marker id '  fm.dev--Two!!  ' (sanitization + uppercase) --
workspace/tab label: 2M-FM-DEV-TWO

-- Second mate home, malformed/blank marker (must never impersonate primary's 1M-FIRSTMATE) --
workspace/tab label: 2M-UNKNOWN

-- Ordinary crewmate/scout task label (unchanged, lowercase, never collides with an uppercase mate label) --
example crewmate tab label: fm-a1b2c3

-- Projection-ordering jq helper accepts both legacy and new-format parent labels --
{
  "new_primary": true,
  "new_secondmate": true,
  "old_primary": true,
  "old_secondmate": true,
  "crewmate_never_a_parent": false
}

Pipeline

Updates from git push no-mistakes

Summary by CodeRabbit

• New Features

  • Introduced clearer Herdr workspace labels: 1M-FIRSTMATE for primary workspaces and 2M-<SCOPE> for secondmate workspaces.
  • Secondmate task tabs now use their corresponding workspace labels.
  • Invalid or missing secondmate identifiers are labeled UNKNOWN.
  • Workspace ordering recognizes both new and legacy label formats.

• Documentation

  • Updated configuration, naming conventions, upgrade guidance, and verification references for the new labels.

• Tests

  • Expanded coverage for label normalization, workspace placement, isolation, recovery, and legacy compatibility.